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PREFACE 


This reference manual describes STSC's Nested Arrays System, an 
experimental research implementation of APL developed to explore 
extensions to the APL language. Among other proposals this system 
offers nested arrays, arrays in which each position can contain an array 
of any rank. Nested arrays can conveniently represent data which is 
difficult to represent in conventional APL data structures. 


The purpose of this research is to develop extensions to APL which 
will make APL programmers more productive. The concepts in this manual 
can also be used to model processes which will later be rewritten in APL 
or another language. Explore and evaluate these concepts and use them 
to extend your thought tools. 


The process of implementing the Nested Arrays System has focused on 
producing a fully functional system rather than an efficient system. 
Operating efficiency will be addressed at a later time. 


STSC currently plans to offer the research implementation until 
January 1982. Selected features from this system will be provided in 
STSC's production APL*PLUS VM System. 


Among the many people whose ideas are included in this system are 
J. A. Brown, Kenneth E. Iverson, Michael A. Jenkins, E. E. McDonnell, 
Trenchard More, and Bob Smith. The Nested Arrays System was implemented 
by Bob Smith. 


I would like to thank those who spent many hours reviewing earlier 
versions of this manual: Tom Edelson, Paul Jackson, Bob Korsan, Gene 
Mannacio, Bob McGhee, Don Scheer, and Roy Sykes, Jr. I am especially 
grateful to John Gilmore, Graham Prindle, Laurie Russell, Barbara 
Schick, and Bob Smith who contributed many useful items. 


Carl Cheney 
San Francisco 
March 1981 
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CHAPTER 1 


INTRODUCTION 


This manual describes STSC's Nested Arrays System, a research 
implementation of APL designed to explore extensions to the APL 
language. Both the system and the manual are intended for use by 
experienced APL programmers. 


The manual is divided into six chapters. Chapter 1 introduces the 
major concepts of the system in an informal tutorial manner. In 
addition, Section 1.4 describes how to gain access to the system, and 
Section 1.5 describes the syntax conventions used in the remainder of 
the manual. 


Chapters 2 through 5 contain detailed reference material for the 
functions, operators, and features provided in the system. Chapter 6 
explains how conventional APL functions and operators work on nested 
arrays. Following Chapter 6 is a glossary and a list of references. 


1.1 What Are Nested Arrays? 


In conventional APL, each position of an array can contain only a 
simple scalar. In a nested array, each position can contain an array of 
any rank. The term for the contents of a position of an array is item. 
For example, 


A 

(1 2 3) (2 4 6) (3 6 9) (4 8 12) 
pA 

4 
x 

(123 ¢ 7 8 9 

uy 5 6) 10 11 12) 

ox 

2 


The variable A is a four-item vector, each of whose items is a 
three-item vector. The parentheses indicate where items begin and end. 
The variable ¥ contains a two-item vector, each of whose items is a 
two-row, three-column matrix. 


These arrays are said to be nested or nonsimple. A simple array is 
one in which there is no nesting; that is, each position contains an 
unnested scalar. The simple function, represented by the symbol = 
used monadically, returns 1 if its argument is simple and 0 otherwise. 


A 


15 


In addition to the simple function, the Nested Arrays System 
provides other tools for dealing with nested arrays. Sections 1.1.1 
through 1.1.5 introduce five of these tools: four new functions 
(enclose, disclose, pick, and type) and a new feature (strand notation). 
These tools are covered in more detail in Chapters 3 and 5. 
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1.1.1 Enclose 


The enclose function, represented by the symbol ¢ used monadically, 
creates a nested scalar out of any array which is not a simple scalar. 
A simple scalar is returned unchanged. 


Beci1 2 3 
B 

(1 2 3) 
po pB 

0 
=B 

A a 
cect 2 

( (1 2)) 
ch 

4 
=xch 

; = 
Ce(ctWHAT'),(c'HATH'),(¢'GOD'),c'WROUGHT'! 
ec 

4 


Cc 
(WHAT) (HATH) (GOD) (WROUGHT) 


1.1.2 Disclose 


The disclose function (monadic >) undoes the work of the enclose 
function. It removes the outermost nesting from a nested scalar and 
returns the enclosed item. 


>B 
1 2 3 
p>B 
3 
=B 
0 we 
z2BRB 
1 
ac! ABC! 
ABC 
ped 
5 
25 
§ 
A[2] 
(2 4 6) 
2A 2] 
2 4% 6 


When disclose is applied to an array that has more than one iten, 
it returns only the first item; in fact, used in this context another 
name for disclose is first. 


223 4 
2 

2A 
123 
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Lads Pies 


The pick function (dyadic >) extracts a portion of an array. Each 
successive item of the left argument selects a successively deeper- 
nested item of the right argument. 


A 

(14 2 3) (2 4 6) (3 6 9) (4 8 12) 
324 

3.6 9 
3.224 

6 


When picking from an array that is not a vector, the corresponding 
item of the left argument must have a shape equal to the rank of the 
array. For instance, to select an item from a matrix, the item in the 
left argument must be a two-item vector. 


x 
(4123 ¢€( 7 8 9 
uy 5 6) 10 11 12) 
12X 
4.323 
uo 5 6 
(1,¢2 3)>X 


1.1.4 Strand Notation 


Strand notation is a means of representing both simple and 
nonsimple vectors. It is based on the familiar notation for entering a 
constant numeric vector (for instance, 4 8 12). Strand notation takes 
effect when two or more of the following constructs appear in an 
expression without an intervening function: 


° A numeric value: for example, 256. 
© A character value; for example, 'SLITHY TOVES'. 
° An expression; for example, (2*0.5). 


When two or more such constructs appear with no function separating 
them, each becomes an item. 


(2x3) (3+4) 
6 7 
pE«'PICK' 'A' "CARD! 
3 
(PICK) A (CARD) 
E<2 0 Fe3 9 G#5 
EFG 
2.3 5 
EP Gx2 
4 6 10 
(2 3) (4 5 6) (7 8 9 10) 
(2 3) (4 5 6) (7 8 9 10) 


Notice that when an item evaluates to a simple scalar, it remains 
simple. 
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1.1.5 Type 


The type function (monadic T) returns a result with the same 
structure as its argument. However, numeric values are replaced with 
zeros and character values are replaced with blanks. 


TU 
0 00 0 
' tet tPONDER' 
1i14%i1%1.1 
TA 
(0 0 0) (0 0 0) (0 0 0) (0 0 0) 
TC 


( ) ( ) ( ) ¢ ) 


1.2 How Existing Functions and Operators Work on Nested Arrays 


Scalar functions are pervasive; that is, they apply through all 
levels of nesting. 


A 
(1 2 3) (2 4% 6) (3 6 9) (4 8 12) 
At+A 
(2 4 6) (4% 8 12) (6 12 18) (8 16 24) 
Ati 2 3 4 
(1 2 3) (1 2 3) (1 2 3) (1 2 3) 
Ani 


(0 4 2) (1 3 5) (2 5 8) (3 7 11) 
1 2 3 4xcl 2 3 
(1 2 3) (2 4 6) (3 6 9) (4 8 12) 


Structural functions apply to the outermost level of a nested 
array. 


2 290A 
(1 2 3) (2 4% 6) 
(3 6 39) (4 8 12) 
A 
(4 8 12) (3 6 9) (2 4 6) (1 2 3) 


Operators can also be applied to nested arrays. In the following 
example, the addition function has been applied to the items of 4 in the 
pattern specified by the reduction and scan operators. 


+/A 
(10 20 30) 
+\A 
(1 2 3) (3 6 9) (6 42 18) (10 20 30) 


Two new features in the Nested Arrays System allow operators to 
call user-defined functions and all primitive functions. 


When user-defined functions are called by operators, powerful yet 
easily understood array-oriented control structures are provided for 
function calls. This new feature can also be used to explore the 
behavior of an operator as in the following example. 
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VY Z«L MINUS R 
C41] ZeL-R 
[2] 2'f2,<->,22,<=>,02' OFMT(L; #32) 


v 
5§ MINUS 3 
5- 32 2 
2 
“/15 
3 
MINUS/ 15 
ye Sa 74 
3-742 4 
Q- he 2 
1- = 3 
3 


By allowing operators to call any primitive function, the 
restriction of operators to scalar functions is eliminated. 


s/'MARES' 'RAT' 'OATS! 
(MA RESEATOATS) 
2>,/'MARES' 'EAT' ‘OATS! 
MARESEATOATS 
123 0,., 4% 5 
(1 4) (4 5) 
(2 4) (2 5S) 
(3 4) (3 5) 


Operators have restrictions about the valence (the number of 


arguments) of the functions which are their arguments; for instance, 
reduction requires that its left argument be a dyadic function. 


1.3 New Operators 
Many new operators are included in the Nested Arrays System; only a 


few are described in the following sections. New operators are covered 
in detail in Chapter 4. 


1.3.1 Dyadic Reduction 


The left argument of dyadic reduction indicates the width of the 
window on which reduction is performed. For example, a left argument of 
2 indicates that reduction should be performed on consecutive pairs of 
items in the right argument. 


2¢/114141 
3 +7414 1 
h+/ tdi. 
2</123 4 


Af 2</ 1 2 2 3 Returns 1 if argument is strictly ascending. 
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If the left argument is negative, each window is reversed before 
being reduced. 


“2 -/ 4 324 
die, 


1.3.2 Dyadic Scan 


adic scan is similar to dyadic reduction. With dyadic scan, 
however, leading items of the result are produced by reducing vectors 
shorter than the length specified in the left argument. The window 
starts with a single item and grows, one item at a time, until it 
reaches the length specified in the left argument. Because of this, the 
result has the same shape as the right argument. 


34#\ 44411 
123 3 3 

2<\ 3 4 2 
3.1 0 

(+A+#\0 0 1 0 
0011410010 


2 *\ A Inverse of #\ on Boolean arguments. 
00100010110 


1.3.3 Each 


The each operator applies a function to the items of its argument 
or between the items of its arguments to produce the items of its 
result. The each operator is represented by the dieresis symbol ("). 


123 p° 4 56 
(4) (5 5) (6 6 6) 
123,°4 56 
(1 4) (2 5) (3 6) 
O+R+(2 3 5) (7 11 13) 
(2 3 5) (7 11 13) 


oR 

CP 24,18) 235) 
ae 

(52 2) 43 4957) 
o> R 


(13 11 7) (5 3 2) 


The each operator can accept as its argument a derived function 


such as plus-reduction. In fact, any operator can accept any derived 
function. 


+/" R 
10 31 


The next example builds a five-item vector, each of whose items is 
a two-item vector. Each two-item vector is an argument to the [FREAD 
function. The result is a five-item vector, each of whose items is a 
component read from the file. 


FILE*OFREAD” (+ 2 ,° 15 
(2 1) (2 2) (2 3) (2 4) (2 5) 
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1.3.4 Power Limit 


Power limit, represented by overstriking the symbols “ and *, 
executes a monadic function repeatedly using the result of one iteration 
as the argument to the next until the result is identical twice ina 
row. This result is returned. 


Power limit can be used for converging series calculations or for 
loop-until-done computations. 


V R+INPUT DATA 
C1] R+DATA,U 
V 


RESULT+INPUT*e 10 


fs 
2 3 5 
es 
7 11°13 17 
Cs 
10 
oRESULT 
7 


1.4 Gaining Access 


To gain access to the Nested Arrays System, log on to STSC's 
APL*PLUS VM System and enter the following commands: 


~DEPENE~SPORAG Eb Me 
NARS 


The system will respond with: 


APL*PLUS SERVICE 
NESTED ARRAYS SYSTEM 


CLEAR WS 
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1.5 Syntax Conventions Used in This Manual 


Function and operator symbols are shown exactly as they appear in 
actual usage. Symbols such as parentheses are shown if required. Other 
symbols that appear in syntax displays-and definitions are 


An operator's left argument when an array. 

An operator's right argument when an array. 

An operator's left argument when a function. 

An operator's right argument when a function. 

The inverse of a function. 

A counter which iterates through the indices of an argument. 
A counter which iterates through the indices of an argument. 
The selected coordinate of a function or operator. 

A function's left argument (the function may be a derived 
function). 

A function's right argument (the function may be a derived 
function). 

A result. 


we TRY NOM Ph 


Ss 


The examples shown below illustrate the use of these syntax 
conventions. 


ZuR The monadic unique function. 

Z«L=R The equivalent function. 

Z+L £/ (K] R Dyadic reduction with explicitly selected 
coordinate. 

Z+(f£*B) R The power operator. 

ZL £Vg R The dual operator. 


Definitions are given either in textual form or in an equivalent 
expression. A symbol common to the syntax and definition represents the 


same argument. For example, the syntax, %+¢f\R for scan could be defined 
as ZL I]+«£/r+R. 


In some definitions, such as the above definition of scan, argument 
and result ranks are assumed even though the function or operator 
extends to arrays of other ranks. The assumed argument rank is the 


lowest rank which displays the salient characteristics of the function 
or operator; extensions to higher ranks are noted. 


The double~headed arrow (++) indicates tha 
the same meaning or return identical results (f£ 
pL °.f R +> (pL),pR). 


t two expressions have 
or instance, 


Definitions and examples are given in origin 1. 


WS FULL errors are not listed. Also not listed is a [ZO IMPLIcIT 
ERROR signalled because [II0 is localized and not defined and an 
expression such as +/[1]A4 has been executed. In such a situation the 
error is in the axis selection rather than in the plus-reduction (the 
expression +/A executes without error). 
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CHAPTER 2 


SET FUNCTIONS 


The group of functions called set functions manipulate vectors 
based on a comparison of their items. None are sensitive to [ICT. 
Consequently, the arrangement of the result is not affected by [CcTr. 


Each of the set functions deals with ordered sets; that is, the 
order of the arguments is reflected in the order of the result. 


The set functions are 
° Unique, which returns the unique items of its argument. 


° Set difference, which returns the items in its left argument not 
found in its right argument. 


e Union, which returns the items in its left argument followed by 
the items in its right argument that are not found in its left 
argument. 


°0 Intersection, which returns the items common to both arguments 
in the order they appear in the left argument. 


Nested Arrays System 
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2-1 Unigue 


Syntax 
Z2euR 


Definition 


Z«((Rif)=1pR)/R 


Discussion 


The unique function returns the unique items of its argument. 


Argument and Result 


The argument is a vector; a scalar is coerced into a one-item 
vector. The result is a vector with as many items as there are unique 
items in the argument. 


Examples 


u'OH MY MY' 
OH MY 

U'PIDDLE' 'DEE' 'DEE' 'FIDDLE' 'DEE' 'DuM! 
(FIDDLE) (DEE) (DUM) 


Errors 


RANK ERROR The argument is of rank greater than one. 
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2.2 Set Difference 


Syntax 


Z+L~R 


Definition 


Z2¢(-LeR)/L 


Discussion 


Set difference returns items of its left argument that are not 
found in its right argument. 


Arguments and Result 


Both arguments are vectors; scalars are coerced into one-item 
vectors. The result is a vector with as many items as there are in the 
left argument that are not found in the right argument. 


Examples 


'FLING'~' NOEL" 
PIG . 

'SQUEEZ B13 
SQUEEZE 

'FIDDLE' ‘DEE! 'DEE' ‘FIDDLE' '‘DEE' 'DUM' ~ c'DEB! 
(FIDDLE) (FIDDLE) (DUM) 


Errors 


RANK ERROR One or both arguments have rank greater than one. 
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2.3 Union 


Syntax 
Z*LuR 


Definition 
ZL ,R~L 


Discussion 


Union returns its left argument followed by those items of its 
right argument that are not found in its left argument. 


Arguments and Result 


Both arguments are vectors; scalars are coerced into one~item 
vectors. The result is a vector with as many items as there are in the 
left argument plus the number of items in the right argument that are 
not found in the left argument. 


Example 


"BUFF' u'BOON! 
BUPFOON 


Errors 


RANK ERROR One or both arguments have rank greater than one. 
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2-4 Intersection 


Syntax 
Z2*L aR 


Definition 
Z¢(LeR)/L 
Discussion 
Intersection returns those items that are common to its arguments 


in the order in which they appear in its left argument. 


Arguments and Result 


Both arguments are vectors; scalar arguments are coerced into one~ 
item vectors. The result is a vector with as many items as the 
arguments have in common. 


Example 


'HAIR'n' RAID! 
AIR 


Errors 


RANK ERROR One or both arguments have rank greater than one. 
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CHAPTER 3 


MISCELLANEOUS FEATURES 


The Nested Arrays System provides many new features. Among the 
ones described in this chapter are 


Qo 


Heterogeneous arrays -- arrays that can be composed of both 
numeric and character data. 


Ambivalant user-defined functions ~~ user-defined functions that 
can be called either monadically or dyadically. 


Expanded display potential -- allows suppression of the results 
produced by executing functions. 


Strand notation -~ a means of representing both simple and 
nested vectors. 
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3.1 Zilde 


Definition 


10 


Discussion 


Overstrike: O~ 


Zilde is the constant empty numeric vector. 


Examples 
+/6& 

0 
ZtML OA; ] 
6 = pA 

0 
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Gives the identity element of addition. 


Reshapes 4 into a scalar so that a row 
of the matrix M will be selected 
as a vector. 


Is A a scalar? 
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3.2 Catenation along the First Dimension 


syntax 


ZeLsk Overstrikes: 27 


Definition 


Z<«L,(OIO] RF 


Discussion 


The behavior of catenation is unchanged; 3; is an abbreviation for 
specifying catenation along the first dimension, just as / and © are 
abbreviations for specifying reduction and rotation along the first 
dimension. 


Example 
'GOB'; 2 3p'ITRENET' 
GOB 


IRE 
NET 


Errors 


Errors that are possible with catenation are also possible with 
catenation along the first dimension. 
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3.3 Heterogeneous Arrays 


Definition 


Heterogeneous arrays are arrays that can be composed of numeric 
data intermixed with character data. 


Discussion 


The concept of heterogeneous arrays permits APL arrays to be 
partially numeric and partially character in any desired pattern. This 
opens up a number of new possibilities for arranging data. 


The concept of heterogeneous arrays should not be confused with the 
concept of nested arrays. An array can be simple but heterogeneous. 


Examples 


'SMTWTFS's ' 's 5 Tp! ',130 
S M T W T FPF § 


1 2 3 4 
5 6 7 8 910 11 
12 13 14 15 16 17 18 
19 20 21 22 23 24 25 
26 27 28 29 30 


Student numbers and corresponding grades may be stored as follows: 


AtlLh42 3146 9931 8674.4 29'A C-B+F * 
A 

1442 A 

3146 CH 

9931 B+ 

8674 F 
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3.4 Type 


Syntax 
Z2*TR 


Definition 


Type replaces characters in its argument with blanks and numbers 
with zeros. 


Argument and Result 


The argument is any array. The result has the same structure as 
the argument. 


Examples 


(+A¢?2 3p10 


me OT 


' tery ' BLIMP! 
1iidaiti.ti 
AtT'ONEY' , 4& , *¥YoU! 
Ast { 
1121031141 
A=0 
0000141000 
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Definition 


Sink absorbs its argument without displaying it. If sink is used 
in a traced function line, the value is displayed. 


Discussion 


Sink allows you to discard an unwanted value without resorting to 
reshaping the value into an empty matrix or assigning it to a system 
variable. 


Example 


«DL 3x60 © 'THE EGGS ARE READYS' 
THE EGGS ARE READY} 
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3.6 Ambivalent User-Defined Functions 


Syntax 
V {LEFT} FUNCTION RIGHT 


Definition 


An ambivalent user-defined function has braces around the left 
argument name in its header. It can be called monadically or 
dyadically. When called monadically, its left argument is not defined; 
a VALUE FRROR is signalled within execution of the user-defined function 
if the left argument is referenced prior to being set. 


Discussion 

This feature permits creation of user-defined functions which can 
be called monadically or dyadically. When called monadically the 
function can either assume a default left argument or exhibit different 


behavior. Testing to see if the left argument was provided can be done 
by using the system function [VC (name class). 


Examples 
V Z+{L} DIV R 
C4] 2(0=0NWC 'L')/'hei' © Z+LtR 
V 
3 DIV 4 
DIV 4 
V {FNS} FNREPL REPL;... 


Ci] >(0#0NC 'FNS')pL1 > FNS*ALLFNS 
[2] Di: ... 
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3.7 Enhanced Display Potential 


A function that has braces around the result name in its header 
returns a result with display potential off. For example, 


VY (RESULT)«<FUNCTION 


This result is not displayed automatically in an executing 
function. It is displayed if returned by a function line which is 
traced. 


This feature can be used when a function returns a useful result 
but when it would not be useful for this result to be displayed by 
default. For example, 


VY {Z2})«L FAPPENDR R 
[1] Z+200FSIZE RO L OFAPPEND R 


V 
'GNU' DFCREATE 9 
"PIRLJ' FAPPENDR 3 
1 
V FOO 
C1] 'LE? IT BE' FAPPENDR 9 
V 
POO 
2°20FSIZE 9 
3 


In addition, certain system functions, when called from an 
executing function, return results that are not displayed automatically. 
The functions are [DEF, [IDEFL, ODL, DERASE, OFX, OFX, OLocK, OSIGWAL, 
Osve (in its dyadic form), Osvo, Osvr, and (WAIT. 


The main purpose of these system functions is to produce a side 
effect rather than a result. Results of these system functions are 
displayed if the statements that call them are traced or if the 


functions are executed in immediate execution mode. For example, 
VG 
C1] Dex 'At 
Vv 
At 
One ‘a! 
2 
OFX 'At 
1 
OWe 'A! 
0 
Acs 
G 
One ‘At 
0 
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3.8 Reshape Extended 


Syntax 


Z2*L oR 


Definition 


When the right argument of reshape is an empty array, the fill item 
of the right argument is supplied in each position of the result. 


Discussion 


When the right argument is empty, reshape returns fill items in the 
shape specified by the left argument. This makes it possible to define 
the fill item for an array as TOpR. 


Examples 
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3.9 Equivalent 


syntax 


Z2+L=k Overstrike: = 


Definition 

Equivalent returns l if the left and right arguments are identical 
in rank, shape, items, and (if empty) prototypes. It returns ) 
otherwise. Equivalent is sensitive to oer. 
Discussion 

Equivalent compares two arrays and determines whether they are 


identical in all respects. 


Arguments and Result 


The arguments can be of any rank, shape, and type. The result is 
scalar 1 or 0. Equivalent is sensitive to oer. 


Examples 
8= 10 
1 _ 
Qgztt 
0 a 
O= ,0 
0 ~ . 
Ate2 30'CATDOG' 
A=A 
t = 
A=14 
0 ~ 
(2 309! ')=TA 
1 


The last example shows a useful technique for verifying that the 
structure and type of a value (perhaps an argument to a function) are 
what was expected. 


Errors 


(Cr IMPLICIT ERROR (er is localized but not defined. 
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3.10 Inequivalent 


Syntax 

Z2*L#R Overstrike: = 
Definition 

2+~L=R 


Inequivalent is sensitive to [lcr. 


Discussion 


Inequivalent returns 1 if its arguments are different in any 
respect and 0 if they are identical. 


Arguments and Result 


The arguments can be of any rank, shape, and type. The result is a 
scalar l or 0. Inequivalent is sensitive to [IC7. 


Examples 
8410 
23 4 1 # 2 39'CATDOG! 


Set yt 


Errors 


OCT IMPLICIT ERROR OCT is localized but not defined. 
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Sell Strand NOtation 


Definition 


Strand notation is a means of representing vectors, either simple 
or nested. Three kinds of constructs appear in strand notation: 
numeric values such as 12, constant character vectors such as 
‘HT ERONYMUS BOSCH', and expressions such as (PICKLExJUICE). When two or 
more of any of these are adjacent, each is interpreted to be an item. 
constructs which evaluate to simple scalars remain simple. 


Discussion 


Strand notation is an extension of the familiar notation used to 
enter a constant numeric vector. A position can now consist of a number 
(as before), a character scalar or vector, Or an expression. An 
expression may need to be enclosed in parentheses to limit its scope. 


Note that nesting occurs only when two or more constructs are 
adjacent. 


Examples 


All of the following examples (excluding the initial assignment) 
return three-item vectors. 


A<1l © B+2 0 C#3 9 Del 2 3 


ABC 
1 23 
A B D 
12 (1 2 3) 
A B Cx2 
24 6 
A B D+10 
i412 (42 22-13) 
A B (D+10) 


12 (11 12 13) 
(19 4 1) 4 ‘you! 
(49 4 1) 4 (YOU) 
A 'SNARK' 3.14 
1 (SNARK) 3.14 
(2 3) 4 § 
(2 3) 4 5 
5 tat tyt 
5 =V 
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3.12 Strand Notation Assignment 


Syntax 
C D E«R 


Definition 


Strand notation assignment allows more than one variable to be 
assigned in one operation. Each variable to the left of the assignment 
arrow receives the corresponding item of the vector to the right. A 
single-item right argument is coerced into a vector with one item for 
each variable name on the left. 


Arguments 


The right argument is a vector with as many items as there are 
names to the left of the assignment arrow. 


Examples 
A Cel 
A 


B 2 3 
OBO C 


GW ND 


A B C+lYOUR APPEARANCE" 'IS'\ OUR BUSINESS' ) 
ABC. | | 
(YOUR APPEARANCE) (IS) (OUR BUSINESS) 


A O+#C A Exchange the values of A and ¢. 
ABC 


(OUR BUSINESS) (IS) (YOUR APPEARANCE) 


V {FNS} FNREPL REPL:... 
[4] eo 8 © 
[2] L£1:0LD NEW+REPL © ... 


Errors 


LENGTH ERROR The right argument does not have the same number 


of items as there are names to the left. 


RANK ERROR The right argument is of rank greater than one. 
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CHAPTER 4 


NEW OPERATORS 


Operators are APL language constructs which operate on one or two 
arguments and produce derived monadic or dyadic functions. Derived 
functions usually provide different capabilities than the function or 
functions which were operated on. 


A familiar example is +/R. The reduction operator takes the plus 
function as its argument and produces a monadic function which then 
operates on its argument RF. In this example, the operator's left 
argument is addition and the (derived) function's right argument is &. 


The operators that follow are new rules for deriving functions. 
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4.1 Behavior of Operators 


Sections 4.1.1 through 4.1.3 outline some of the enhancements in 
operator behavior in the Nested Arrays System. 


4.1.1 Accepting User-Defined Functions 


User-defined functions can now be called by operators. This opens 
up many new possibilities for using operators as array-oriented control 
structures for executing defined functions. 


For example, the function FDIT is called once for each item of 
TEXT. 


EDIT TEXT 


4.1.2 Accepting Any Primitive Function 


Formerly, operators could only accept scalar functions as their 
arguments. Removing this restriction is possible because existing 
operators have been redefined in such a way that they can return nested 
results. See Chapter 6 for details. 


4.1.3 Operator Sequences 


Operators have long left scope and short right scope. An operator 
takes as its left argument the function or derived function to the left. 
Parentheses may be used to limit the scope of an operator by 
interrupting the sequence. An operator takes as its right argument only 
the first function to its right. Parentheses may be necessary to 
lengthen an operator's right argument. Constrast this with functions 
which have long right scope and short left scope. 


In the following example the each operator (see Section 4.10) takes 
as its left argument the derived function of reduction acting on 
addition. 


+/" (1 2) (3 4) (5 6) 
3.7 11 


In the next example the right argument of the dual operator is 100 
composed with the multiplication function. (The dual operator is 
discussed in Section 4.15, and composition is discussed in Section 
4.14.) The parentheses are necessary to make dual the primary operator 
and the function derived from composition as its right argument. The 
effect of the expression is to truncate digits to the right of the 
hundreth place. 


L¥(1000x) 3.14159 
3.14 


The short right scope of the composition operator makes the 
expression +°3x2 equivalent to (+°3)*x2, which is equivalent to (*2)+3. 


+o 3x? 
L+.x.tR «> B(+.%) eR 
+,x/R «> (+,%*)/R 
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4.2 Dyadic Reduction 


Syntax 


Z+L £/ BR 
ZL £7 R 
Z2+L £/ [kK] R 


Definition 
For (L20)ALspZ: 

ZEQI]« £/ RU(T-1)+1. 5) 
For (L<O)A(|L)<pZs: 

Z20Q1+ £/ ORE (I-1)+i-L] 

When the magnitude of the function's left argument is greater than 
the length of the selected coordinate of the right argument, an empty 
array results. 

Dyadic reduction extends to arrays of any rank by selecting the 
direction of the vectors to be reduced via the axis operator. 
Discussion 

Dyadic reduction performs reductions on the items in a "window", 
whose length is specified by the function's left argument. The window 
moves across the items in the right argument, one position at a time. 
For example 3 +/ 1 2 3 4 5 6 performs four plus-reductions, each on 


windows of width three and returns (1+2+3),(2+3+4), (2+4+5) ,44+5+6. 


If the function's left argument is negative, the items in each 
window are reversed before the reduction is done. 


Using 2 or “2 as the function's left argument is an especially 
useful case which applies a function between consecutive pairs of items 
in its argument. For instance, the expression A/ 2 </ VY returns 1 if 
all the items in V are in ascending order and A/ 2 =/ V returns 1 if all 
the items in V are equal. 


Arguments and Result 


The function's left argument is an integer-valued scalar. The 


operator's left argument is a dyadic function. The function's right 
argument is an array. 


The shape of the result is the shape of the function's right 


argument in all coordinates except the one reduced. The length of that 
coordinate (the Kth coordinate) is given by Of (pR)(K]+1-|L. 
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Examples 


NR RF Om © 
+ 
™ 
fas 


+/ 4 
ca eae 


yo+/ 4 


pe a ode et 


1 


1 


1 


1 


1 


1 


“a>/i1 34 4 5 6 8B 2 


1io0%411 0 


Ze(N+/V)EN 


Errors 


DOMAIN ERROR 


INDEX ERROR 


SYNTAX ERROR 


RAWK ERROR 
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Unweighted moving average. 


The left argument is not simple and integer- 
valued. 


The selected coordinate does not exist in the 
function's right argument. 


The operator's left argument is not a dyadic 
function. 


The function's left argument is not scalar. 
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4.3 Dyadic Scan 


Syntax 
2eL £\ PR 
ZeL £\ FB 
Z+L £\ CK] RB 
Definition 
ZeX,L £/ PR 
Where X[I]«(2*«L) £/ I+tR; for Teil(pR)L1+{L. 


Dyadic scan extends to arrays of any rank by selecting the 
direction of the vectors to be scanned via the axis operator. 


Discussion 

Dyadic scan is similar to dyadic reduction. With dyadic scan, 
however, leading items of the result are produced by reducing vectors 
shorter than the length specified by the function's left argument. The 
window starts with a single item and grows, one item at a time, until it 
reaches the length specified in the left argument. From that point on, 
the result is identical to the result produced by dyadic reduction. 

If the function's left argument specifies a length greater than the 
selected dimension of the function's right argument, dyadic scan behaves 


as though the magnitude of the function's left argument is equal to the 
selected dimension of the function's right argument. 


The following identities illustrate possible uses of dyadic scan. 
2 #\ is the inverse function of #\ for Boolean arguments. 
“2 «\ is the inverse function of +\. 


“2 #\ is the inverse function of x\ for non-zero arguments. 


Arguments and Result 


The function's left argument is an integer-valued scalar. The 


function's right argument is an array. The result has the same shape as 
the function's right argument. 


Examples 

: rc rr es Oe 
iiaid1ti 

2*\ 1411 
12 2 2 

3 #\ 1 i411 
1 2 3 3 

h+\ 1411 
4123 4 
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cme ee ee oe 


123 4 

Errors 

DOMAIN ERROR The left argument is zero. 
The left argument is not simple and integer- 
valued. 

SYNTAX ERROR The operator's left argument is not a dyadic 
function. 

RANK ERROR The left argument is not scalar. 
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4.4 Convolution 


Syntax 


Z+L ftg R Overstrike: T” 


Definition 
20 IT]+« £/(O(0FIF-pR)¥(IL pL) tLig (Ol l-pL)+¥(IL pk) ter 


The above expression describes convolution when the function's left 
and right arguments are vectors; the extension to arrays of higher rank 


is similar to that of inner product except that the two inner dimensions 
are merged. 


Discussion 


The convolution operator performs a moving window inner product 
with the selected items of the left argument reversed. When the left 
and right arguments are vectors, the first items of the result are 


ZCij+« £/ £01] g RE1] 
2021+ £/ L[2 1] g Rf1 2] 
Z(3]« £/ L[3 2 1] g R[1 2 3] 


° 


Arguments and Result 


The operator's left and right arguments are dyadic functions. The 
left and right arguments of the derived function are arrays of any rank. 
The shape of the result is given by (“14pL),("1+( 1tpL )+1+pR),14pR. 


Examples 


The following example performs polynomial miltiplication. The left 
and right arguments are vectors of coefficients. The result is the 
coefficients of the product polynomial. 


123 47x 4 567 
4 13 28 34 32 21 


The following example illustrates how the result above was 
computed. The operator's right argument is produced using direct 
definition. 


TIMES€'(3 08 +/ a * w),tt © 4/ Tt, (wa),t' «x Ptypw O axa! 
123 + T (TIMFSV°) 4 5 67 
ho +e ¢/ 1 x 4 
13 «> ¢+/ 24% 4 5 
28 <> +/3 214% 4 5 6 
3H «> +/ 324% 567 
32 «> +/ 32x 67 
24 «> +4+/ 3% 7 
4 413 28 34 32 24 
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Another way to interpret the expression Z«L +Tx R is to consider 
the right argument to be a vector of weights. The result is a weighted 
moving average. Contrast this with the unweighted moving average given 
as an example in dyadic reduction (Section 4.2). 

Convolution can also be used to define [9S as follows: 


AQSS B «+ (pA) t(1-pB)¥("1+pB)+ AAT=OB 


Errors 


DOMAIN ERROR The inner dimension of each argument is zero. 
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4.5 Mask 


syntax 


Z+L (Ae/) R 
Z+L (Ae#) R 
Z«L (Ae/[K]) R 


Definition 


A negative value in the operator's left argument selects the 
corresponding item from the function's left argument; a positive value 
selects the corresponding item from the function's right argument. The 
magnitude of a value in the operator's left argument indicates how many 
times to repeat a selected item. A zero in the operator's left argument 
leaves out the corresponding item in the function's left and right 
arguments. 


When the function's left and right arguments are of rank greater 
than one, the vector operator's left argument selects or removes slices 
of the arrays along the designated coordinate. 


Discussion 
Mask chooses between items of its function's left and right 


arguments based on values in its operator's left argument. Items can be 
repeated or left out entirely. 


Arguments and Result 


When the three arguments are vectors, they are all of equal length. 
The operator's left argument contains integers. A scalar argument is 
reshaped to match the shape of a nonscalar argument. The shape of the 
result (possibly after the operator's left argument has been extended) 
is given by +/|A. 


When the function's left and right arguments have rank greater than 
one, their shapes must be identical. The operator's left argument is an 
integer-valued vector with the same length as the selected dimension. 
When the function's left or right argument is a scalar, it is reshaped 
to match the shape of the other argument. When the operator's left 
argument is a scalar, it is reshaped to be a vector the length of the 
selected dimension of the function's arguments. The shape of the result 
has the shape of the function's left and right arguments in all 
dimensions except the selected one, which has Length +/|A- 


Examples 
'ABCDEF' ("1 2 073 1 Oe/) 1123456! 
A22DDD5 


'GEAD' (1 “1 2 “1e/) 'FROG' 
FLOOD 
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D+A+4 39 'ABCDEFGHISKL ' 
ABC 
DEF 
GHI 
JKL 
«B+ 39'0123456789! 
012 
345 
678 
904 


012 
012 
DEF 
SKE 
JKL 
JKL 
A ("3 0 te/) B 
AAA2 
DDDS 
GEG8 
JSASL 


Errors 


DOMAIN ERROR The operator's left argument is not simple and 
integer-valued. 


INDEX ERROR The selected coordinate does not exist in the 
function's left or right argument. 


LENGTH ERROR The three arguments are not conformable. 


RANK ERROR The operator's left argument is not a vector or 
scalar. 
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4.6 Replicate Extended 


Definition 
Ze(etoR) (Le/) R 
Z<«(ctoR) (Lee) R 
Ze(ct2R) (Le/{K]) # 
Discussion 
Replicate has been extended to allow negative values in the left 


argument to select the fill item of the right argument. The concept of 
fill item is discussed in Section 6.9. 


Arguments and Result 


The left argument to replicate is a simple integer-valued vector 
the same length as the selected dimension of the right argument. The 
right argument is an array. A scalar left or right argument will be 
reshaped to the length of the other argument. The result has the shape 
of the right argument in all dimensions except the selected one; the 
length of that dimension is given by +/I|L. 


Examples 
1°72 4/2 31 
2001 . 
O4ii1021 14 14101 / 'WONDERLAND! 
ONE LAD 
Errors 
DOMAIN ERROR The left argument is not simple and integer- 
valued. 
INDEX ERROR The selected coordinate does not exist in the 
right argument. 
LENGTH ERROR The left and right arguments are not conformable. 
RANK ERROR The left argument is not a vector or scalar. 
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4.7 Mesh 


Syntax 


Z+L (Ae\) R 
Zh (Ae\) R 
Z*«L (A°\EK]) RB 


Definition 


The operator's left argument to mesh is a control vector which 
indicates how the function's left and right arguments are to be 
interleaved and where fill items of the function's right argument are to 
be inserted. 


The Ith positive value of the operator's left argument selects the 
Ith item of the function's right argument. The Jth negative value of 
the operator's left argument selects the Jth item of the function's left 
argument. A zero in the operator's left argument indicates that a fill 
item from the function's right argument is to be inserted. Except for a 
zero, the magnitude of a value in the operator's left argument indicates 
how many times to repeat a selected item of the function's left or right 
argument. 


Mesh extends to arrays of rank greater than one by merging together 
slices of the function's left and right arguments as directed by the 
selected coordinate and the operator's left argument. 


Discussion 
Mesh merges its function's left and right arguments, possibly 


repeating items and possibly inserting fill items of the function's 
right argument. 


Arguments and Result 


The operator's left argument is an integer-valued vector or scalar. 
For vectors: 


pL +> +/A<0 
oR +> +/A>0 
og «+> +/1! IA 


The function's left and right arguments must match in all 
dimensions except the selected one which follows the rules for vectors. 


A scalar left or right argument is reshaped to the shape of the 
nonscalar argument in all dimensions except the selected one which is 
determined by the rules for vectors. 


The result has the same shape as the function's left and right 


arguments except along the selected dimension which follows the rule for 
vectors. 
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Examples 


‘Tt (4 "4 2 “1 2 “1 2 “Le\) 'MSSP! 
MISSISSIPPI 

42(72 “104 2 3e\) 7 89 
14207889939 

'BIB' (71 “1 1 711014121 1 10\) 
BILBO BAGGINS 


Errors 


DOMAIN ERROR The operator's left 


integer~-va lued. 
LENGTH 


ERROR The argument shapes 


RANK ERROR The operator's left 
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'LOBAGINS' 


argument is not simple and 


are not conformable. 


argument is not a vector. 
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4.8 Expansion Extended 


Syntax 


2*L \ R 
ZL \ BR 
ZL \CKI R 


Definition 


Z<(ctT>R) (Le\) BR 
Z«(ctT2R) (Le) R 
Z<«(er>R) (Le\[K]) RB 


Discussion 


Expansion has been extended to allow the left argument to be 
integer-valued. (In conventional APL, the left argument is restricted 
to Boolean values.) If a negative value occurs in the left argument, 
the fill item of the right argument is selected for the result; if a 
positive value occurs in the left argument, an item is selected from the 
right argument. The magnitude of values in the left argument indicates 
the number of times an item of the right argument or a fill item is to 
be included in the result except that 0 and “1 have the same effect 
which is to include one fill item. 


Arguments and Result 


The left argument is a simple integer-valued vector. The number of 
positive values must equal the selected dimension of the right argument. 
The right argument is an array. The result has the shape of the right 
argument in all dimensions except the selected one which is given by 
+/1P |Z. 


Examples 


112141171 £1 1°12 °\ ‘BUTTERFLY! 
BUTTER FLY 


201411472 1\1 234 
11020300 4 
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Ve Commu te 


Syntax 


Zel £~ R Overstrike: ~ 


Definition 


ZR £ L 


Discussion 


Commite causes the left and right arguments to a function or 
derived function to be exchanged before being presented to the function. 
It is of use mainly in sequences of operators. 


Ar gume nt and Result 


Tre function or derived function argument of commite must be 
dyadic. 


Examples 
3-4 
1 
[5] 2L3 /~ @=0A Read the /~ as "if" (branch 
to 53 if A is scalar). 
-/4123 4 5 
3 
1-2-3-4-5 
3 oe 
-~ ft 23 4 5 
“5 
V Z2«L CSUB FR 
[1] 2¢R-L 
V 
CSUB/ 1 23 4 5 
“5 
( ( (8-4 )-3)-2)-1 
“5 
Errors 
SYNTAX ERROR The left argument of commite is not a dyadic 


function. 


System 
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4.10 Each 


Syntax 
Ze f° R 


Z+ Lb £° R 
Definition 


I>Z «+ £ Tok 
[2% <*> (foL) £ IR 


Por Leip. 


Discussion 


The each operator applies a function to its arguments item by item. 
This provides the power of scalar extension to any function. Note that 
the scalar extension applies only to the outermost level; each does not 
produce a pervasive derived function. 


Arguments and Result 


In the dyadic form, the function's left and right arguments must be 
scalar conformable; the shape of the result is determined by the same 
rules that apply to scalar functions. 


Examples 
123 4 4° 5 678 

(5) (6 0) (7 0 0) (8 000) 
A 

((1 2 3) (4 § 6)) ((7 8 9) (10 11 12)) 
oA 

((7 8 9) (10 11 12)) ((1 2 3) (4 5 6)) 
o A 

((4 5 6) (1 2 3)) ((10 414 412) (7 8 9)) 
o A 

((3 2 1) (6 5 4)) ((9 8 7) (12 11 10)) 
> A 

((1 2 3) (4 5 6)) ((7 8 3) (10 11 12)) 
12348," § 67 8 

(1 5) (2 6) (3 7) (4H 8) 
2, 14 


(2 1) (2 2) (2 3) (2 4) 


In the following example, TIFENO is catenated, item by item, to the 
items of 110. The result is a ten-item vector, each of whose items is a 
two-item vector. Next, the function [FREAD is applied to each two-item 
vector. The final result is a ten-item vector containing the first ten 
components of the file tied to fIENO. 


C+ FREAD TIENO,” 110 


Copyright 1981 STSC, Inc. ~42— Nested Arrays System 


Errors 


LENGTH ERROR The function's left and right arguments are not 
conformable. 


RANK ERROR The function's left and right arguments are not 
of compatible rank. 
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4.11 Power Operator 


Syntax 


Z+(f*B) R Overstrike: *" 


Definition 


2ef f f . . . ER 
or 
2h hh... he’ 


The operator's left argument is a monadic function which is applied 
to the function's right argument the number of times specified by the 
right operator argument. If the operator's right argument is negative, 
the inverse of the function (represented by h above) is applied the 
number of times specified by the magnitude of the right operator 
argument. If the operator's right argument is zero, the function's 
right argument is returned unchanged. 


Arguments 


The operator's left argument is a monadic function. The operator's 
right argument is an integer-valued scalar. The function's right 
argument is an array. 


Examples 
(+/*3) 2 2 2 21 


V ReFIB A 
[1] «a CALCULATE THE NEXT TERM IN THE FIBONACCI SERIES 
[2] R+A,+/ 244 

V 


(FPIB*15) 1 1 Calculate the next 15 terms. 
112 3 5 8 13 21 34% 55 89 4144 233 377 610 987 1597 


[+B<+\ 1111 2 
12346 

(+\*74) B 
11112 


The following expression conditionally reshapes A into a two by 
five matrix if A is scalar; otherwise A is returned unchanged. 


A+(2 5ep*(@=04)) A 
The parentheses around 6=pA are necessary because without further 


direction the short right scope of the power operator would take only 
the zilde as the operator's right argument. 
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Errors 


DOMAIN ERROR The operator's right argument is not integer- 
valued. 


The operator's left argument is not an invertible 


function. 
RANK ERROR The operator's right argument is not a scalar. 
SYNTAX ERROR The operator's left argument is not a monadic 
function. 
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4.12 Power Limit 


syntax 


Z« fko R Overstrike: *” 


Definition 
Leek EOE ve ee SER 


The operator's left argument is a monadic function which is 
repeatedly applied to the function's right argument using the result of 
one iteration as the argument to the next until the result is identical 
twice in a rov. This result is returned. The derived function produced 
by this operator is sensitive to [ICT. 


Discussion 


Power limit is useful for converging series calculations or other 
loop-until-done computations. 


Arguments 


The operator's left argument is a monadic function. The function's 
right argument is a value to be applied to the derived function. 


Examples 


? *© 1091000 
Po te et 


VY Z+SQRT A 
[1] a CALCULATE SQUARE ROOT USING NEWTON'S METHOD 
[2] Z+AO('0.5xXutatw! Vo) xod 
V 


SQRT 2 
1e414213562 
2*065 
1,.414213562 


Errors 

SYNTAX ERROR The operator's left argument is not a monadic 
function. 

OC? IMPLICIT ERROR cr is localized but not defined. 
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4.13 Power Series 


Syntax 


Ze fig R Overstrike: *° 


Definition 
42¢l f R £€ (R f£.g R) £ (Rk f£.g9 R f.g RA) £... 
fo is a matrix the shape of the right function argument with g/@ 
on the diagonal and f/8® elsewhere. Inner products are repeatedly 


performed until the accumulation is identical twice in a row. 


The derived function produced by this operator is sensitive to [C?. 


Discussion 


The power series operator does a series of inner products between a 
square matrix and itself. The successive inner products are accumulated 
until the result is identical twice in a rw. 


This operator gets its name from series like 


1+ X + (X*2) + (X¥*3) + 2. 2 


Arguments and Result 


The operator's arguments must be dyadic functions with identity 
elements. The function's right argument must be a square matrix. The 
result has the same shape as the function's right argument. 


Example 


A network of nodes with one-way connections can be represented as a 
Boolean matrix with 1's marking the connections. For example, a l in 
the second row, third column, would indicate that there is a direct path 
from node two to node three. If the reverse path exists, it would be 
represented by a l in the third row, second column. 


If this matrix is stored in the variable WET, the possible journeys 
of two jumps are computed by NETV.ANET. Journeys of three jumps are 
computed by NEIV.ANETV.ANET and so forth. The expression V*ANEP? 
computes all possible journeys of any length. For example, 


NET 


oo ceo 
Or Oo © 
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The preceding matrix indicates that the following one-way moves are 
possible: 


1 to 3 


3 to 2 
2 to 4 


Here are the journeys of length two: 
NETV .ANET 


E 
0 
0 
1 
0 


ooo °o 
Ooo Or 


And length three: 


NETV .ANETIV .ANET 


ooo oc 
Oooo eo 


All possible journeys of any length (including zero) are 
accumulated into one matrix as follows: 


VERA NEP 
1idai 
o101 
O11 
0001 
Errors 
DOMAIN ERROR There is no identity element for one or both of 
the operator's arguments. 
RANK ERROR The function's right argument is not a matrix. 
SYNTAX ERROR One or both of the operator's arguments are not 
dyadic functions. 
OCT IMPLICIT ERROR cr is localized but not defined. 
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4.14 Composition 


syntax 
2+ feg R 
Z+L fog R 
Z+ (f£°B) R 
Z« Aeg R 


Definition 


Ze f gk 
Z2«¢L £ Gg R 
Ze Rf B 
Ze AghR 


Discussion 


Composition assembles functions and arguments to form derived 
functions. This provides the glue with which to put together functions 
and arguments so that operator's arguments can be more complex than 
single functions. 


Examples 
(*o2) 10 The square function. 
100 
(*°0,5) 100 The square root function. 
10 
+/o 1 
10 


In the following example, +/ and 1 are composed to form a monadic 
derived function which adds up iota vectors. This derived function is 
applied by the each operator, item by item, to the values in the right 
function argument. 


+/or 1 24 


1 3 10 
Zthoh” V Produce a ranking vector for each item of Y/Y. 
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4.15 Dual 


Syntax 
z+ £¥g R Overstrike: Vv” 
Z+L £4¥g R 

Definition 


Zh fgR 
Zeh(gL)£gGR 


The inverse of the function g is represented by h. 


Discussion 


Dual applies the operator's right argument which is a monadic 
function separately to each argument of the derived function, applies 
the operator's left argument to the result of that, then applies the 
inverse function of the operator's right argument to the result. 


In a physical context this is comparable to opening a drawer, 
altering its contents, and then closing the drawer. 


Arguments 


The function which is the operator's right argument must have an 
inverse. Since inverses cannot be computed for user-defined functions, 
a user-defined function cannot be used as the right function to dual. 


Examples 


pA+' DELETE TRAILING BLANKS’ 
30 

C+B+(v\V¥> Azt ')/A 
DELETE TRAILING BLAWKS 


oB 
22 
LV¥(1000x) 3.14159 
3.44 . 
4/V(x02) 3 4 Pythagorean theorem. 
5 
Errors 
DOMAIN ERROR The operator's right argument is not an 
invertible function. 
SYNTAX ERROR The function which is the operator's right 


argument has the wrong valence. 
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4.16 Function Table 


syntax 
Z+o.g RF 


pefinition 
Ze> e.g/ 1 R 
or 
Z+(112h) ¢.g (123R) %.9 4. » 
The derived function produced by the function table operator is 


sensitive to fTo. 


Discussion 


The function table operator applies a designated outer product 
between the iota vectors of each item of its argument. 


Examples 
0, x3 6 
1 2 3 y § 6 
2 4 6 §8 10 12 
3 6 912 15 18 
©, =4h & 
100 0 
010 0 
001 0 
“O30 Oe 
©, ,2 5 


Ci De, OY le BE, de Ck SD 
(2 1) (2 2) (2 3) (2 4) (2 5) 


Errors 

SYNTAX ERROR The operator's right argument is not a dyadic 
function. 

(120 IMPLICIT ERROR Mr0O is localized but not defined. 
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4.17 Direct Definition 


Syntax 


Z< (VB) R Wane 
Z+L (AVe) R 0 
Z« (AVB) R 
ZL (AVB) R 


Definition 


Direct definition produces a derived function from the expressions 
contained in the character vector argument or arguments. 


A character vector to the left of the operator represents a dyadic 
definition; one to the right represents a monadic definition. If both 
appear, an ambivalent function is created. Otherwise, a jot replaces 
the unused argument and a derived function of fixed valence is created. 


Each character vector argument contains one or more APL 
expressions. The symbols alpha (a), omega (w), and underscore ( ) 
represent respectively the left argument, the right argument and the 
function itself. Alpha and omega contain the arguments to the function 
and can be reassigned. Alpha cannot be used in monadic definitions. 
Underscore permits recursive definitions. 


If colons appear in a character vector, they serve to group series 
of expressions. The result of the group of expressions before the first 
colon must be a simple integer scalar or vector containing no negative 
values. This determines the sequence in which the remaining groups of 


expressions are executed. The remaining groups are numbered beginning 
with zero. 


The result of the function is the result of the last expression 
executed, 


Discussion 


Direct definition is a convenient means of creating temporary 
functions, especially for use as arguments to operators. 


Arguments and Result 


Each argument to the operator is a simple character vector or 
scalar; a scalar is coerced to a one~item vector. 


The result of the function is the result of the last expression 
executed, 


If colons appear in the definition, the result of the group of 
expressions before the first colon must be a simple integer scalar or 
vector which contains no negative values. 
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Examples 


(oV'(+/w)tpw') 2 4 6 Monadic-only average function. 


(oV'(+/w)tpw')” (2 4 6) (10 40 30 50) (1 2) 
(4) (32.5) (1.5) 


Detatw' © Me? 4 a! 


3 (DVM) 4 Ambivalent function equivalent to the 
0.75 * symbol. 
(DVM) 4 
0.25 
MINetar>w 3: a 3 at 
3 (MINV°) 4 Dyadic-only minimum function. 
3 
4 (MINVo) 3 
3 


(eV'w=0 : wx wel : 1')” 0123 4 5 6 Factorial. 
1 12 6 24 120 720 


At(eoV'0O 200:1902:3 04 : 50 6') 256 


0 

§ 

6 

1 

2 

1 

A 

2 

Errors 

DOMAIN ERROR An argument to the operator is not simple and 
character. 
The result of the expressions to the left of the 
first colon is not simple and integer-valued. 

INDEX ERROR The result of the expressions to the left of the 
first colon did not select an existing group of 
expressions. 

RANK ERROR An argument to the operator is not a scalar or 
vector. 
The result of the expressions to the left of the 
first colon is not a scalar or a vector. 

SYNTAX ERROR The derived function was called with a valence 
for which it was not defined. 
The a symbol appears in the monadic definition. 

VALUE ERROR The last expression executed did not return a 


result. 
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CHAPTER 5 


NESTED ARRAY FUNCTIONS 


The functions described in this chapter manipulate nested arrays in 
various ways. Among the functions included in this chapter are 


° Enclose, which creates nested scalars. 
° Disclose, which removes a layer of nesting. 
° Pick, which selects objects from nested arrays. 


° Split, which lowers the rank of an array by enclosing a 
coordinate. 


° Mix, which raises the rank of an array by disclosing and 
inserting a coordinate. 


° Choose, which can index scattered points of any rank array. 
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5.1 Enclose 


Syntax 
Zeck 


Definition 


Enclose turns any array except a simple scalar into a nested 
eealae. A sample eealar ig returned unchanged. For any other array, a 


layer of nesting is applied and a nonsimple scalar is returned. 


Discussion 


Enclose and disclose are the fundamental operations that create and 
dissolve nested arrays. Enclose can be thought of as putting a scalar 
wrapping around an array. Enclose returns a simple scalar argument 
unchanged; a nonsimple scalar or an array of rank greater than zero is 
enclosed into a nonsimple scalar. 


Argument and Result 


The right argument can be any array. The result is a scalar. 


Examples 


é5 
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5.2 Disclose 


syntax 
Z4>R 


Definition 


Disclose returns the first item of an array or the fill item if the 
array is empty. 


Discussion 


Disclose is the inverse function of enclose; that is, R+«> >cR, It 


removes the scalar wrapping from a nested scalar, revealing the item 
within. 


When the argument to disclose is an empty array, disclose returns 
the prototype or fill item (see Section 6.9) for the array. Disclose 
applied to an empty array is also called extract. 


When the argument to disclose is not an empty array, disclose 
operates only on the first item of the array; that is, 2A «> 29 pA. 
Disclose applied to an array which has more than one item is also called 
first. 


When the argument to disclose is simple, disclose returns the first 
item or the fill item as a scalar. 


Argument and Result 


The argument is any array. The result is the first item within the 
array. 


Examples 


D4 5 6 
y 

A 
(9. PB) 3G2.-3: 4) 

DA 
97 5 

2>0p¢2 3p 16 
00 0 
00 0 
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5.3 Partitioned Enclose 


Syntax 


Z2*LcR 
Z<«Le(K] R 


Definition 


Io@ «> (T=+\L)/(K] PR 


Discussion 


Partitioned enclose builds a nonsimple vector out of selected 
portions of an array. The leading item of the left argument does not 
have to be 1; the first selected portion begins where the first 1 
appears. 


Arguments and Result 


The left argument is a Boolean vector with the same length as the 
selected coordinate of the right argument. A scalar left argument is 
reshaped to match the selected dimension of the right argument. The 
right argument is an array of any rank. The selected dimension of the 
right argument must equal the length of the left argument. The result 
is a vector of length +/L containing the selected portions of the right 
argument. 


Examples 


M+4+0O 0 101100cC¢123484 5 67 8 
(3 4) (5) (6 7 8) 


pA 
3 
ici 2 3 
(1) (2) (3) 
104 ¢f1] 3 49112 
C4234 € 8 10-12 42) 
5 6 7 8) 
Errors 
DOMAIN ERROR The left argument is not simple and Boolean. 
LENGTH ERROR The length of the left argument does not ma tch 
the selected dimension of the right argument. 
RANK ERROR The left argument is not a vector. 
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5-4 Pick 


Syntax 
Z2+LoR 


Definition 


@2R «> F 
L2R «> (14L)2>R[@oL] 


This function is sensitive to [Iro. 


Discussion 


Pick indexes portions of an array through any number of layers of 
nesting. The right argument is an array to be "picked through". The 
left argument is a vector, each item of which indexes through a layer of 
nesting in the right argument. 


For example, in the expression 2 3>(1 2 3) (4 5 6), the 2 selects 
the second item, which is the vector 4 5 6, and the 3 selects the third 
item of that vector; the result is the simple scalar 6. 


The shape of each item in the left argument must equal the rank of 
the array which has been picked up to this point, except that a scalar 
item is coerced into a one item vector which can pick from a vector. In 
particular, only an enclosed empty vector can pick a scalar. 


Arguments and Result 


The right argument is any array. The left argument is an integer- 
valued vector which may be nonsimple. The result is the portion of the 


right argument which is selected by the left argument. Pick is 
sensitive to [ro. 


Examples 


A 


((1 2) 3 4) ((2 4) 6 8) ((3 6) 9 12) 
((4 8) 12 16) ((5 10) 15 20) ((6 12) 18 24) 
A=9>A 


(<2 1)>A4 
(4-8) 412 16 
((¢2 1),1)>4 


4 8 

((¢2 1),1 2)>4 
8 

3= (c8)>3 
4 pes 
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Errors 
DOMAIN ERROR 


INDEX ERROR 


LENGTH ERROR 


RANK ERROR 


OLOQ IMPLICIT ERROR 
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The left argument is not integer-valued. 


The left argument selects nonexistent positions 
of the right argument. 


The shape of an item of the left argument does 


not match the rank of the selected portion of the 
right argument. 


The left argument or an item of the left argument 
is not a scalar or vector. 


flO is localized but not defined. 
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Z*+=R Overstrike: = 


Definition 
Z+R=cR 
Discussion 
Simple returns a scalar 1 if the argument is simple and a scalar 0 


otherwise. 


Argument and Result 


The argument is any array; the result is a Boolean scalar. 


Examples 
Fig 
1 
ze13 
0 


Copyright 1981 STSC, Inc. ~60= Nested Arrays System 


5.6 Not-Simple 


Syntax 


Z+#R Overstrike: # 


Definition 


ZeRec R 


Discussion 


Not-simple returns a scalar 1 if the argument is not simple anda 
scalar 0 otherwise. 


Examples 
#13 


42013 


Copyright 1981 STSC, Inc. ~61~+ Nested Arrays System 


5.7 Split 


Syntax 

2¢vF 

Zev CK] R 
Definition 

Split encloses a dimension of an array. The rank of the result is 
one less than that of the argument. Each item of the result is a vector 


with the length of the enclosed dimension. 


A simple scalar is. returned unchanged; a nested scalar is enclosed 
once more and its rank remains 0. 


Discussion 
The split function segments an array along a coordinate into a 


nested array. 


Argument and Result 


oZ <> (K#ippk)/pR 


p2Z <> (pRIIK] 


Examples 


43 4o 112 
(1 23 4) (5 6 7 8) (9 10 11 12) 
pA«+2 3 4p 124 


2 3 
poA 
ut 
pAe¥[2] 2 3 49112 
2 4 
pA 
3 
Errors 
INDEX ERROR The selected dimension does not exist in the 


argument. 
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 §.8 Mix 


syntax 


Ztth 
Zet+(K] BR 


Definition 


Mix assembles the arrays which are the items of its argument. 
These arrays have identical shape. A fractional number within brackets 
specifies the two dimensions between which the additional coordinates 
are to be inserted. The result is an array with additional dimensions 
inserted between the specified ones. The added dimensions have the 
shape of the items of the right argument. 


Discussion 
Mix assembles the items of an array into a higher~dimensional array 


with one less level of nesting. 


Argument and Result 


The right argument is an array consisting of identically shaped 
items. The shape of the result is the shape of the argument with the 
shape of the items inserted between the specified dimensions. 


Examples 


#(1 2 3 4) (5 6 7 8) (9 10 11 12) 
2 23) 
5 6 7 8 
10 11 12 

pt+ 3 090 


= 


© 


ot 1 2p¢3 490 
123 4 

otfi.5] 1 2p¢3 4p0 
1 3 4 2 


Errors 


INDEX ERROR The selected dimensions do not exist in the 
argument. 


LENGTH ERROR The items in the argument are not conformable. 
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5.9 Choose (Indexing Extended) 


syntax 
Z«L(T] 


LUI) +z 
Definition 


When indices within brackets are not simple, each item is a vector 
which forms an index to the array being indexed. 


No semicolons are permitted within the brackets when the indices 
are not simple. 


Choose is sensitive to fro. 


Discussion 


Each item of the array within brackets is a vector the length of 
the rank of the array being indexed. Scattered points of any array can 
be indexed by this function. In particular, scalars can be indexed by 
enclosed empty vectors. 


Arguments and Result 


The argument to the left of the brackets is an array of any rank. 
The argument within brackets is an array, each item of which is a vector 
of the same length as the rank of the indexed array. Expressed 
differently, (A/2=/p",I)A(poL)=p2I. The result or the value being 
assigned into the array has the same shape as the indices unless a 
scalar is being assigned. In this case, the scalar is reshaped to match 
the shape of the indices. Each item within brackets must form a valid 
index to the left argument array. Choose is sensitive to Oro. 


Examples 
5[ 
§ 
§ 
N+A+3 4p i112 
3. 4 
11°12 
ALT(3 2) (1 4) (2 3)] 
10 4 7 
AL 2p “131+0 


3° 4 
7 8 
0 
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Errors 


DOMAIN ERROR The argument within brackets is not integer- 
valued. 

INDEX ERROR An item of the argument within brackets does not 
form a valid index to the left argument. 

LENGTH ERROR The length of an item of the argument within 
brackets is not equal to the rank of the left 
argument. 


The shape of the argument within brackets does 
not match the shape of the array being assigned. 


RANK ERROR The rank of the array within brackets does not 
match the rank of the array being assigned. 


O7OQ IMPLICIT ERROR FO is localized but not defined. 
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5.10 Index Generator Extended 


Syntax 
Zeik 


Definition 


Zo, ,R 
or 7 
Z+> 0, ,/ 1 R 
The index generator is sensitive to (0. 
Discussion 


The argument to monadic iota can now be a vector. Iota returns a 
result such that 4 «+ Afipd4] where A can be of any rank. 


Argument and Result 


The argument to the index generator must be a simple integer-valued 
vector or scalar. A scalar argument is coerced into a one~item vector. 
The value of the argument determines the shape of the result; that is, 

R <> pik. 
cf 


Example 
13° 4 

(1 1) (1 2) (4 3) (1 4) 

(2 1) (2 2) (2 3) (2 4) 

(3 1) (3 2) (3 3) (3 4) 
Errors 
DOMAIN ERROR The argument is not simple and integer-valued. 
RAWK ERROR The argument has rank greater than one. 
Oro IMPLICIT ERROR {FO is localized but not defined. 
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CHAPTER 6 


EXISTING FUNCTIONS AND OPERATORS ON NESTED ARRAYS 


This chapter describes how the functions and operators in 
conventional APL implementations operate in the Nested Arrays System. 
On simple arguments, functions and operators behave no differently than 
the primitives on the APL*PLUS System. Operators acting on scalar 
functions and simple arguments also are not changed. 
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6.1 Scalar Functions 


Syntax 
2eL £ R 
2¢ £8 
Definition 


f2>Z «> (f>2L) £ IR 
[2% +> f TR 


Discussion 
Scalar functions are pervasive through nested arrays; that is, they 


apply to the data through every level of nesting. 


Arguments and Result 


At each level of nesting, scalar conformability rules apply and 
determine result shapes. 


Examples 


(2 ae 8 OB) de Ce a G8 
Ces ee ar ce me 

(1. 3 2) 4 + 3 (5 3 2) 
(4 6 5) (9 7 6) 


A 
Cay 2. AS) 6) OE CO FS (tO 21) ) 
3 4) 
Ax2 
Coe i ORO ADS BPE (4B oO oo) ) 5 
6 8) . 
Errors 
LENGTH ERROR The arguments do not follow scalar conformability 
rules. 
RANK ERROR The ranks of the arguments do not conform. 
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6.2 Reduction 


Syntax 


Z+£/R 
Z+f/R 
Z«f£/CKIR 


Definition 

For a one~item vector: 
Z+@ oR 

Otherwise: 


Z¢c(2R)f£2£/14R 


Discussion 


The specified function operates between the items of the array. 
Another way to represent the behavior of reduction is 


2ec(1>R) £ (2>R) f£ . . «. £ (pR)OR 


Arguments and Result 


The operator argument is no longer required to be a scalar function 
because enclosing the result permits reduction's result shape rules to 
be followed. The right argument is not necessarily simple. 


Examples 


+/{(1 2 3) (4 5 6) (7 8 9) 
(12 15 18) 

€/'LAZARUS LONG' "ROBERT HEINLEIN' 
(100010014 4 1 0) 


Errors 

DOMAIN ERROR The function has no identity element and 
reduction along a dimension of length zero was 
attempted. 

SYNTAX ERROR The function specified is not dyadic. 
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6.3 Scan 


Syntax 
Z2<f\R 
Z*fXR 
Z+f\CKIR 
Definition 


ZL I]+f£/I+k 


Discussion 
The redefinition of reduction affects the behavior of scan. The 


operator argument is not limited to scalar functions since the function 
is applied between items of the argument and the result is enclosed. 


Arguments and Result 


The operator's argument can be any dyadic function. The right 
argument need not be simple. The result has the shape of the argument 
and is not necessarily simple. 


Example 
*\(1 2 3) (4 5 6) (7 8 9) 
CE 2B CSF, 280e CL 2 ALS) 28) 
Errors 
SYNTAX ERROR The operator argument is not dyadic. 
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6.4 Inner Product 


Syntax 
ZL f.g R 


Definition 


Zef/ Lg R 


Discussion 


The redefinition of reduction, scalar, and other functions also 
affects inner product. 


Arguments and Result 


The operator's arguments can be any dyadic functions. The 
arguments follow the usual conformability rules but need not be simple. 
The result follows inner product's usual rules and need not be simple. 


Example 


12-28 Sh glk oS 26 
{1 4 2 5 3 6) 


Errors 

DOMAIN ERROR A reduction of an empty argument was attempted 
for a function which has no identity element. 

SYNTAX ERROR One or both operator arguments are not dyadic 


functions. 
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6.5 Outer Product 


syntax 
Z+L o,f FP 


Definition 


Z{Isd]+c(l>L) £ JR 


Discussion 


Outer product applies a function which is the operator's right 
argument between the items of the arguments to produce the corresponding 
item of the result. 


Arguments and Result 


The operator's right argument must be a dyadic function. The shape 
of the result is (as before) the shape of the left argument catenated to 
the shape of the right argument. 


Examples 


(1 2) (3 4) o.+ (5 6) (7 8) (9 10) 
(6 8) (8 10) (10 12) 
(8 410) (10 12) (12 14) 
1 2 30, ,4 5 6 7 
(1 4) (1 5) (4 6) (1 7) 
(2 4) (2 5) (2 6) (2 7) 
(3 4) (3 5) (3 6) (3 7) 


Errors 


SYNTAX ERROR The operator's right argument is not a dyadic 
function. 
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6.6 Catenation and Lamination 


syntax 
Z2+L,R 
Z2¢L 7h 
2+L,CKIR 
Definition 


Either or both arguments may be nonsimple and heterogeneous. 


Example 
(1 2 (4 5),(1 2 3) 'y! 
(1 2 3) (4% 5) (1 2 3) ¥ 
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6.7 Dyadic Iota and Epsilon 


Syntax 


Z*Lik 
Z2*LeR 


Definition 


The definitions of dyadic iota and epsilon are changed by replacing 
= with =. 


Discussion 


Dyadic iota and epsilon compare their arguments at all levels of 
nesting. The result of each function is simple. The shape of the 
result is based on the shapes of the argument. 


Examples 


A 
(BARBARA) (BOB) (CARL) (GRAHAM) (JESSIE) (JOE) (JOHN) (LAURIE) (PAUL) 
(SCOTT) 
B 
(JESSIE) (SCOTT) (FLOYD) (JUDY) (BOB) (JOE) 
AeB 
0ot1004710001 
AiB 
§ 10 it 11 2 6 


VY PUNCTION; QELX;: ERRORS; HANDLERS 
[1] ERRORS+' DOMAIN FRROR' 'LENGTH ERROR' ‘RANK ERROR! 
[2] HANDLERS*DE LE RE OTHER e LABELS TO HAWDLE ERRORS 
[3] QELX+' +HANDLERSCLERRORS\¢ (A\QDMZOPCNWL) /ODMI! 


6 
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6.8 Structural Functions 


Definition 


The left argument must be simple; the right argument need not be. 
Each function applies at the outermost level only. Fill items for LoR 
L/R L\R and LtR are given by cT2R. (See Section 6.9 for more 
information on fill items. ) 


Examples 


2 3p (1 2) (3 4) 
(1 2) (3 4) (4 2) 
(3 4) (1 2) (3 4) 

1 0 1\(1 2) (3 4) 
(1.2) (0 0) (3 4) 
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6.9 Fill Items 


Definition 
cTOR 
or 
TOR 


Discussion 


The functions which may require fill items are L+R >R L/R L\P 
L(Ae\)R and Lok. The fill item is determined by the type, rank, and 
shape of the first item of the right argument. 


For a nested right argument, the fill item can be arbitrarily 
complicated. For example, 


A 
( (1 1:4) (2 2 2) 
(3 3 3) (4 4 4)) 

3tA 
( (1 11) (2 2 2) (¢ (0 0 0) (0 0 0) ( (0 0 0) (0 0 0) 
(3 3 3) (4 4 4)) (0 0 0) (0 0 0)) (0 0 0) (0 0 0)) 


Even when an array with a nested first item has been emptied, the 
prototype information is kept and can be extracted with any of the 
functions listed above. 
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6.10 Functions Not Defined on Nested Arrays 


Syntax 


Lik 
LTR 
LER 
fk 
AR 
WR 
LER 
wR 
L?R 


All system functions. 


Definition 


These functions will not accept nested arrays as arguments. 


Discussion 


When called by operators, these functions will perform on simple 
items. 


Example 


Av(1 3 4) (6 2 8) (6 6 6) (6 § 2) 
(Ch 29+ Sys a a) 4. OB He ee a) 


Errors 
DOMAIN ERROR An argument is not simple. 
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GLOSSARY 


coercion 
Relaxation of strict rules about the shapes of function arguments. 
This is done to simplify the job of the programmer. For instance, 
strictly speaking the left argument of reshape should always be a 


vector. It simpifies expressions greatly (with no loss in clarity) 
to allow a scalar left argument to be treated as a one-item vector. 


derived function 


The function produced by an operator sequence. 


display potential 
The attribute of a result which indicates whether or not it will be 
displayed automatically. For example, assignment returns a result 


with display potential off; the result is suitable for further 
computation but is not displayed. 


fill items 


The items inserted into arrays by the execution of certain 
functions such as expansion. 


function argument 


An array which is positioned so as to be the left or right argument 
of a function or derived function. For instance, in the expression 
+/R, the variable R is the function argument. Contrast with 
“operator argument". 


heterogeneous 
A simple array containing both numbers and characters. 
item 


A fundamental term which refers to an object of an array. This 
object may be nonscalar, nested, or both. The items of a simple 
array are all simple scalars. 


nested 


A term indicating that one or more items of an array or its 


prototype contain enclosed arrays rather than being composed 
entirely of simple scalars. 
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operator argument 


An array or function which is positioned so as to be the left or 
right argument of an operator. For example, 


in the expression +/&, 
addition is the operator argument. Contrast with "function 
argument". 


operator sequence 


An operator and its arguments. 


: For example plus-reduction is the 
derived function produced by the operator sequence +/. 


prototype 


The fill item for an array. 


simple 


A term indicating that all positions of an arra 


y or the prototype 
of an array contain only scalars that are not nested. An array can 
be simple but heterogeneous. 


structure 


The form of an array determined by 


the shape at all levels of 
nesting and the pattern of nesting. 


valence 


The number of arguments that a func 


tion or operator can accept. 
For example, a function with valenc 


e one is monadic. 
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